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Abstract 
This document describes three abstract Generic Security Service 
Application Program Interface (GSS-API) interfaces used to 
encapsulate/decapsulate context tokens and compare OIDs. This 
document also specifies C bindings for the abstract interfaces. 
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1. Introduction 


The Generic Security Service Application Program Interface (GSS-APT) 
[RFC2743] is a framework that provides security services to 
applications using a variety of authentication mechanisms. There are 
widely implemented C bindings [RFC2744] for the abstract interface. 


For initial context tokens, a mechanism-independent token format may 
be used (see Section 3.1 of [RFC2743]). Some protocols, e.g., Simple 
Authentication and Security Layer (SASL) GS2 [RFC5801], need the 
ability to add and remove this token header, which contains some 
ASN.1 tags, a length, and the mechanism OID to and from context 
tokens. This document adds two GSS-API interfaces 
(GSS_Encapsulate_token and GSS_Decapsulate_token) so that GSS-API 
libraries can provide this functionality. 


Being able to compare OIDs is useful, for example, when validating 
that a negotiated mechanism matches the requested one. This document 
adds one GSS-API interface (GSS_OID_equal) for this purpose. 


Text from this specification can be used as implementation 
documentation, and for this reason, Sections 3, 4, 5, 6, and 8 should 
be considered code components. 


2. Conventions Used in This Document 
The document uses terms from, and is structured in a similar way as, 
[RFC2743] and [RFC2744]. The normative reference to [RFC5587] is for 


the C types "gss_const_buffer_t" and "gss_const_OID"; nothing else 
from that document is required to implement this document. 
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3; 


GSS_Encapsulate_token Call 


Inputs: 

o input_token OCTET STRING -- buffer with token data to encapsulate 

o token_oid OBJECT IDENTIFIER -- object identifier of mechanism for 
the token 

Outputs: 


o major_status INTEGER 


o output_token OCTET STRING -- Encapsulated token data; caller must 
release with GSS_Release_buffer () 


Return major_status codes: 


O GSS_S_COMPLETE indicates that completion was successful and that 
output parameters hold correct information. 


o GSS_S_FAILURE indicates that encapsulation failed for reasons 
unspecified at the GSS-API level. 


GSS_Encapsulate_token() is used to add the mechanism-independent 
token header to GSS-API context token data. 


gss_encapsulate_token 
OM_uint32 gss_encapsulate_token ( 
gss_const_buffer_t input_token, 
gss_const_OID token_oid, 
gss_buffer_t output_token) 


Purpose: 


Add the mechanism-independent token header to GSS-API context token 
data. 


Parameters: 
input_token buffer, opaque, read 

Buffer with GSS-API context token data. 
token_oid Object ID, read 


Object identifier of token. 
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output_token buffer, opaque, modify 
Encapsulated token data; caller must release 
with gss_release_buffer(). 


Function values: GSS status codes 

GSS_S_COMPLETE Indicates that completion was successful and 
that output parameters hold correct 
information. 

GSS_S_FAILURE Indicates that encapsulation failed for 


reasons unspecified at the GSS-API level. 


4. GSS_Decapsulate_token Call 


Inputs: 

o input_token OCTET STRING -- buffer with token to decapsulate 

o token_oid OBJECT IDENTIFIER -- expected object identifier of token 
Outputs: 


o major_status INTEGER 


o output_token OCTET STRING -- Decapsulated token data; caller must 
release with GSS_Release_buffer () 


Return major_status codes: 


Oo GSS_S_COMPLETE indicates that completion was successful and that 
output parameters hold correct information. 


o GSS_S_DEFECTIVE_TOKEN means that the token failed consistency 
checks (e.g., OID mismatch or ASN.1 DER length errors). 


o GSS_S_FAILURE indicates that decapsulation failed for reasons 
unspecified at the GSS-API level. 


GSS_Decapsulate_token() is used to remove the mechanism-—independent 
token header from an initial GSS-API context token. 
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4.1. gss_decapsulate_token 


OM_uint32 
gss_decapsulate_token 


( 


gss_const_buffer_t input_token, 
gss_const_OID token_oid, 
gss_buffer_t output_token) 


Purpose: 


Remove the mechanism-independent token header from an initial GSS-API 


context token. 
Parameters: 


input_token 


token_oid 


output_token 


Function values: 


GSS_S_COMPLETE 


GSS_S_DEFECTIVE_TOKEN 


GSS_S_FAILURE 


buffer, opaque, read 
Buffer with GSS-API context token. 


Object ID, read 
Expected object identifier of token. 


buffer, opaque, modify 
Decapsulated token data; caller must release 
with gss_release_buffer(). 


GSS status codes 


Indicates that completion was successful and 
that output parameters hold correct 
information. 


Means that the token failed consistency checks 
(e.g., OID mismatch or ASN.1 DER length 
errors). 


Indicates that decapsulation failed for 
reasons unspecified at the GSS-API level. 
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5. 


GSS_OID_equal Call 


Inputs: 

o first_oid OBJECT IDENTIFIER -- first object identifier to compare 

o second_oid OBJECT IDENTIFIER -- second object identifier to 
compare 


Return codes: 
o non-O when neither OID is GSS_C_NO_OID and the two OIDs are equal. 


o 0 when the two OIDs are not identical or either OID is equal to 
GSS_C_NO_OID. 


GSS_OID_equal() is used to add compare two OIDs for equality. The 
value GSS_C_NO_OID will not match any OID, including GSS_C_NO_OID 
itself. 


.1. gss_oid_equal 


extern int 

gss_oid_equal ( 
gss_const_OID first_oid, 
gss_const_OID second_oid 


) 
Purpose: 


Compare two OIDs for equality. The value GSS_C_NO_OID will not match 
any OID, including GSS_C_NO_OID itself. 


Parameters: 
first_oid Object ID, read 
First object identifier to compare. 
second_oid Object ID, read 
Second object identifier to compare. 
Function values: GSS status codes 
non-O Neither OID is GSS_C_NO_OID, and the two OIDs 
are equal. 
0 The two OIDs are not identical, or either OID 


is equal to GSS_C_NO_OID. 
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6. Test Vector 


For the GSS_Encapsulate_token function, if the "input_token" buffer 
is the 3-byte octet sequence "foo" and the "token_oid" OID is 
1.2.840.113554.1.2.2, which encoded corresponds to the 9-byte-long 
octet sequence (using C notation) 
"\x2a\x86\x48\x86\x£7\x12\x01\x02\x02", the output should be the 
16-byte-long octet sequence (again in C notation) 
"\x60\x0e\x06\x09\x2a\x86\x48\x86\x£7\x12\x01\x02\x02\x66\x6f£\x6f£". 
These values may also be used to test the GSS_Decapsulate_token 
interface. 
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8. Security Considerations 


The security considerations of the base GSS-API specification 
(([RFC2743]) and the base C bindings ([RFC2744]) are inherited. 


Encapsulation of data does not provide any kind of integrity or 
confidentiality. 


Implementations need to treat input as potentially untrustworthy for 
purposes of dereferencing memory objects to avoid security 
vulnerabilities. In particular, ASN.1 DER length fields are a common 
source of mistakes. 
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